        <!DOCTYPE html>
        <html>
        <head>
                <meta charset="utf-8">
        <title>Configuration class / unittest Library / Dart Documentation</title>
        <link rel="stylesheet" type="text/css"
            href="../styles.css">
        <link href="http://fonts.googleapis.com/css?family=Open+Sans:400,600,700,800" rel="stylesheet" type="text/css">
        <link rel="shortcut icon" href="../favicon.ico">
        
        </head>
        <body data-library="unittest" data-type="Configuration">
        <div class="page">
        <div class="header">
          <a href="../index.html"><div class="logo"></div></a>
          <a href="../index.html">Dart Documentation</a>
         &rsaquo; <a href="../unittest.html">unittest</a> &rsaquo; <a href="../unittest/Configuration.html">Configuration</a>        <div id="search-box">
          <input type="search" name="q" id="q" autocomplete="off"
              class="search-input" placeholder="Search API">
        </div>
        
      </div>
      <div class="drop-down" id="drop-down"></div>
      
        <div class="nav">
        
</div>
<div class="content">
        <h2><strong>Configuration</strong>
          class
        </h2>
        
<button id="show-inherited" class="show-inherited">Hide inherited</button>
<div class="doc">
<p>Hooks to configure the unittest library for different platforms. This class
implements the API in a platform-independent way. Tests that want to take
advantage of the platform can create a subclass and override methods from
this class.</p>
<pre class="source">
class Configuration {
 // The VM won't shut down if a receive port is open. Use this to make sure
 // we correctly wait for asynchronous tests.
 ReceivePort _receivePort;

 /**
  * Subclasses can override this with something useful for diagnostics.
  * Particularly useful in cases where we have parent/child configurations
  * such as layout tests.
  */
 String get name =&gt; 'Configuration';

 /**
  * If true, then tests are started automatically (otherwise [runTests]
  * must be called explicitly after the tests are set up.
  */
 bool get autoStart =&gt; true;

 /**
  * Called as soon as the unittest framework becomes initialized. This is done
  * even before tests are added to the test framework. It might be used to
  * determine/debug errors that occur before the test harness starts executing.
  * It is also used to tell the vm or browser that tests are going to be run
  * asynchronously and that the process should wait until they are done.
  */
 void onInit() {
   _receivePort = new ReceivePort();
   _postMessage('unittest-suite-wait-for-done');
 }

 /** Called as soon as the unittest framework starts running. */
 void onStart() {}

 /**
  * Called when each test starts. Useful to show intermediate progress on
  * a test suite.
  */
 void onTestStart(TestCase testCase) {
   assert(testCase != null);	
 }

 /**
  * Called when each test is first completed. Useful to show intermediate
  * progress on a test suite.
  */
 void onTestResult(TestCase testCase) {
   assert(testCase != null);	
 }

 /**
  * Called when an already completed test changes state; for example a test
  * that was marked as passing may later be marked as being in error because
  * it still had callbacks being invoked.
  */
 void onTestResultChanged(TestCase testCase) {
   assert(testCase != null);
 }

 /**
  * Can be called by tests to log status. Tests should use this
  * instead of print. Subclasses should not override this; they
  * should instead override logMessage which is passed the test case.
  */
 void logMessage(String message) {
   if (currentTestCase == null) {
     // Before or after tests run. In this case we pass null for the test
     // case reference and let the config decide what to do with this.
     logTestCaseMessage(null, message);
   } else {
     logTestCaseMessage(currentTestCase, message);
   }
 }

 /**
  * Handles the logging of messages by a test case. The default in
  * this base configuration is to call print();
  */
 void logTestCaseMessage(TestCase testCase, String message) {
   print(message);
 }

 /**
  * Called with the result of all test cases. The default implementation prints
  * the result summary using the built-in [print] command. Browser tests
  * commonly override this to reformat the output.
  *
  * When [uncaughtError] is not null, it contains an error that occured outside
  * of tests (e.g. setting up the test).
  */
 void onSummary(int passed, int failed, int errors, List&lt;TestCase&gt; results,
     String uncaughtError) {
   // Print each test's result.
   for (final t in _tests) {
     var resultString = "${t.result}".toUpperCase();
     print('$resultString: ${t.description}');

     if (t.message != '') {
       print(_indent(t.message));
     }

     if (t.stackTrace != null &amp;&amp; t.stackTrace != '') {
       print(_indent(t.stackTrace));
     }
   }

   // Show the summary.
   print('');

   var success = false;
   if (passed == 0 &amp;&amp; failed == 0 &amp;&amp; errors == 0 &amp;&amp; uncaughtError == null) {
     print('No tests found.');
     // This is considered a failure too.
   } else if (failed == 0 &amp;&amp; errors == 0 &amp;&amp; uncaughtError == null) {
     print('All $passed tests passed.');
     success = true;
   } else {
     if (uncaughtError != null) {
       print('Top-level uncaught error: $uncaughtError');
     }
     print('$passed PASSED, $failed FAILED, $errors ERRORS');
   }
 }

 /**
  * Called when the unittest framework is done running. [success] indicates
  * whether all tests passed successfully.
  */
 void onDone(bool success) {
   if (success) {
     _postMessage('unittest-suite-success');
     _receivePort.close();
   } else {
     _receivePort.close();
     throw new Exception('Some tests failed.');
   }
 }

 String _indent(String str) {
   // TODO(nweiz): Use this simpler code once issue 2980 is fixed.
   // return str.replaceAll(new RegExp("^", multiLine: true), "  ");

   return str.split("\n").map((line) =&gt; "  $line").join("\n");
 }

 /** Handle errors that happen outside the tests. */
 // TODO(vsm): figure out how to expose the stack trace here
 // Currently e.message works in dartium, but not in dartc.
 void handleExternalError(e, String message) =&gt;
     _reportTestError('$message\nCaught $e', '');

 _postMessage(String message) {
   // In dart2js browser tests, the JavaScript-based test controller
   // intercepts calls to print and listens for "secret" messages.
   print(message);
 }
}
</pre>
</div>
<div>
<h3>Properties</h3>
<div class="field"><h4 id="autoStart">
<button class="show-code">Code</button>
final bool         <strong>autoStart</strong> <a class="anchor-link"
            href="#autoStart"
            title="Permalink to Configuration.autoStart">#</a>
        </h4>
        <div class="doc">
<p>If true, then tests are started automatically (otherwise <a class="crossref" href="../unittest.html#runTests">runTests</a>
must be called explicitly after the tests are set up.</p>
<pre class="source">
bool get autoStart =&gt; true;
</pre>
</div>
</div>
<div class="field"><h4 id="name">
<button class="show-code">Code</button>
final String         <strong>name</strong> <a class="anchor-link"
            href="#name"
            title="Permalink to Configuration.name">#</a>
        </h4>
        <div class="doc">
<p>Subclasses can override this with something useful for diagnostics.
Particularly useful in cases where we have parent/child configurations
such as layout tests.</p>
<pre class="source">
String get name =&gt; 'Configuration';
</pre>
</div>
</div>
</div>
<div>
<h3>Methods</h3>
<div class="method"><h4 id="handleExternalError">
<button class="show-code">Code</button>
void <strong>handleExternalError</strong>(e, String message) <a class="anchor-link" href="#handleExternalError"
              title="Permalink to Configuration.handleExternalError">#</a></h4>
<div class="doc">
<p>Handle errors that happen outside the tests. </p>
<pre class="source">
void handleExternalError(e, String message) =&gt;
   _reportTestError('$message\nCaught $e', '');
</pre>
</div>
</div>
<div class="method"><h4 id="logMessage">
<button class="show-code">Code</button>
void <strong>logMessage</strong>(String message) <a class="anchor-link" href="#logMessage"
              title="Permalink to Configuration.logMessage">#</a></h4>
<div class="doc">
<p>Can be called by tests to log status. Tests should use this
instead of print. Subclasses should not override this; they
should instead override logMessage which is passed the test case.</p>
<pre class="source">
void logMessage(String message) {
 if (currentTestCase == null) {
   // Before or after tests run. In this case we pass null for the test
   // case reference and let the config decide what to do with this.
   logTestCaseMessage(null, message);
 } else {
   logTestCaseMessage(currentTestCase, message);
 }
}
</pre>
</div>
</div>
<div class="method"><h4 id="logTestCaseMessage">
<button class="show-code">Code</button>
void <strong>logTestCaseMessage</strong>(<a href="../unittest/TestCase.html">TestCase</a> testCase, String message) <a class="anchor-link" href="#logTestCaseMessage"
              title="Permalink to Configuration.logTestCaseMessage">#</a></h4>
<div class="doc">
<p>Handles the logging of messages by a test case. The default in
this base configuration is to call print();</p>
<pre class="source">
void logTestCaseMessage(TestCase testCase, String message) {
 print(message);
}
</pre>
</div>
</div>
<div class="method"><h4 id="onDone">
<button class="show-code">Code</button>
void <strong>onDone</strong>(bool success) <a class="anchor-link" href="#onDone"
              title="Permalink to Configuration.onDone">#</a></h4>
<div class="doc">
<p>Called when the unittest framework is done running. 
<span class="param">success</span> indicates
whether all tests passed successfully.</p>
<pre class="source">
void onDone(bool success) {
 if (success) {
   _postMessage('unittest-suite-success');
   _receivePort.close();
 } else {
   _receivePort.close();
   throw new Exception('Some tests failed.');
 }
}
</pre>
</div>
</div>
<div class="method"><h4 id="onInit">
<button class="show-code">Code</button>
void <strong>onInit</strong>() <a class="anchor-link" href="#onInit"
              title="Permalink to Configuration.onInit">#</a></h4>
<div class="doc">
<p>Called as soon as the unittest framework becomes initialized. This is done
even before tests are added to the test framework. It might be used to
determine/debug errors that occur before the test harness starts executing.
It is also used to tell the vm or browser that tests are going to be run
asynchronously and that the process should wait until they are done.</p>
<pre class="source">
void onInit() {
 _receivePort = new ReceivePort();
 _postMessage('unittest-suite-wait-for-done');
}
</pre>
</div>
</div>
<div class="method"><h4 id="onStart">
<button class="show-code">Code</button>
void <strong>onStart</strong>() <a class="anchor-link" href="#onStart"
              title="Permalink to Configuration.onStart">#</a></h4>
<div class="doc">
<p>Called as soon as the unittest framework starts running. </p>
<pre class="source">
void onStart() {}
</pre>
</div>
</div>
<div class="method"><h4 id="onSummary">
<button class="show-code">Code</button>
void <strong>onSummary</strong>(int passed, int failed, int errors, List&lt;<a href="../unittest/TestCase.html">TestCase</a>&gt; results, String uncaughtError) <a class="anchor-link" href="#onSummary"
              title="Permalink to Configuration.onSummary">#</a></h4>
<div class="doc">
<p>Called with the result of all test cases. The default implementation prints
the result summary using the built-in <code>print</code> command. Browser tests
commonly override this to reformat the output.</p>
<p>When 
<span class="param">uncaughtError</span> is not null, it contains an error that occured outside
of tests (e.g. setting up the test).</p>
<pre class="source">
void onSummary(int passed, int failed, int errors, List&lt;TestCase&gt; results,
   String uncaughtError) {
 // Print each test's result.
 for (final t in _tests) {
   var resultString = "${t.result}".toUpperCase();
   print('$resultString: ${t.description}');

   if (t.message != '') {
     print(_indent(t.message));
   }

   if (t.stackTrace != null &amp;&amp; t.stackTrace != '') {
     print(_indent(t.stackTrace));
   }
 }

 // Show the summary.
 print('');

 var success = false;
 if (passed == 0 &amp;&amp; failed == 0 &amp;&amp; errors == 0 &amp;&amp; uncaughtError == null) {
   print('No tests found.');
   // This is considered a failure too.
 } else if (failed == 0 &amp;&amp; errors == 0 &amp;&amp; uncaughtError == null) {
   print('All $passed tests passed.');
   success = true;
 } else {
   if (uncaughtError != null) {
     print('Top-level uncaught error: $uncaughtError');
   }
   print('$passed PASSED, $failed FAILED, $errors ERRORS');
 }
}
</pre>
</div>
</div>
<div class="method"><h4 id="onTestResult">
<button class="show-code">Code</button>
void <strong>onTestResult</strong>(<a href="../unittest/TestCase.html">TestCase</a> testCase) <a class="anchor-link" href="#onTestResult"
              title="Permalink to Configuration.onTestResult">#</a></h4>
<div class="doc">
<p>Called when each test is first completed. Useful to show intermediate
progress on a test suite.</p>
<pre class="source">
void onTestResult(TestCase testCase) {
 assert(testCase != null);	
}
</pre>
</div>
</div>
<div class="method"><h4 id="onTestResultChanged">
<button class="show-code">Code</button>
void <strong>onTestResultChanged</strong>(<a href="../unittest/TestCase.html">TestCase</a> testCase) <a class="anchor-link" href="#onTestResultChanged"
              title="Permalink to Configuration.onTestResultChanged">#</a></h4>
<div class="doc">
<p>Called when an already completed test changes state; for example a test
that was marked as passing may later be marked as being in error because
it still had callbacks being invoked.</p>
<pre class="source">
void onTestResultChanged(TestCase testCase) {
 assert(testCase != null);
}
</pre>
</div>
</div>
<div class="method"><h4 id="onTestStart">
<button class="show-code">Code</button>
void <strong>onTestStart</strong>(<a href="../unittest/TestCase.html">TestCase</a> testCase) <a class="anchor-link" href="#onTestStart"
              title="Permalink to Configuration.onTestStart">#</a></h4>
<div class="doc">
<p>Called when each test starts. Useful to show intermediate progress on
a test suite.</p>
<pre class="source">
void onTestStart(TestCase testCase) {
 assert(testCase != null);	
}
</pre>
</div>
</div>
</div>
        </div>
        <div class="clear"></div>
        </div>
        <div class="footer">
          
        </div>
        <script async src="../client-live-nav.js"></script>
        </body></html>
        
